docs(spec): record DeleteDataRequestSchema's consumer and why the DELETE data door carries no requestSchema - #16191

Fixes #13852

What

One docblock and one changeset. The bare /** Delete Data Request */ header above DeleteDataRequestSchema in packages/spec/src/api/protocol.zod.ts now records the three facts triage's 2026-09-06 ruling (comment 5556446972) asked for. Each was verified on origin/main at d5d8d50db (this PR's base) before being written:

1. Consumer. The schema is the request contract of DataProtocol.deleteData() (protocol.zod.ts:3354 on the base; the DeleteDataRequest alias at :3182). It is consumed statically and parsed at runtime nowhere in the tree — the grep that sees "exported, documented, zero safeParse call sites" is reading the wrong surface, and this card is that grep's filing.
2. Deliberately no REST-door requestSchema, per 请求体从不与声明它的 schema 对照(#3877 的请求侧对偶):7 个 schema 定义了从未启用,而 API 目录已宣称生效 #3899. The catalog's DELETE entry states it in place of the key (plugin-rest-api.zod.ts:1029-1030), and plugin-rest-api.schema-refs.test.ts:77 pins it ("requestSchema appears only on body-carrying methods (POST/PUT/PATCH)"). Read against the real handler (packages/rest/src/rest-server.ts:8558-8591): object and id come from req.params, expectedVersion from req.query or the If-Match header, and req.body is never read.
3. Drift is caught at compile time, not by a runtime parse — [finding] p.deleteData({...} as any) / p.updateData({...} as any) erase the compile-time check of the assembled request against DeleteDataRequest / UpdateDataRequest #15866, landed by PR fix(rest): compile the data doors' protocol requests against the declared contract #16071 (merged; 9b459b791 is on the base). The door's literal is const deleteRequest: ServerScopedDataRequest OF DeleteDataRequest = { ... } (rest-server.ts:8584, generic spelled out for the sanitizer), handed to p.deleteData(deleteRequest) with no cast; the ServerScopedDataRequest docblock (:228-262) states the guard, so the new note points at it rather than duplicating it.

Scope, exactly as ruled: no requestSchema added to any route; the schema is not retired; no other *RequestSchema docblock is touched; no shape, .describe(), or export change. Clause ②: no — the diff is a comment and a changeset; it sits under packages/spec/src/** only because that is where the declaration lives.

Ruling text, verbatim:

交付物(就这一条,⛔ 不要扩):在 protocol.zod.ts:2126 的 /** Delete Data Request */ 上补几句,说明 ① 它的消费者是 DataProtocol.deleteData()(:3354),② 它故意没有 REST 门上的 requestSchema,依据 #3899,并指向 plugin-rest-api.schema-refs.test.ts 那条 pin,③ 门上的漂移由 #15866 / PR #16071 的编译期检查兜住,不是靠运行期 parse。
⛔ 不要顺手给别的 *RequestSchema 加注释——那是另一张卡的人口问题。

Does the docblock project anywhere?

• content/docs/references/api/protocol.mdx: no. The generator renders .describe() strings and the module-level file header, not per-schema docblocks — control: the sibling UpdateDataRequestSchema prose "Modification of an existing record" occurs 0 times in the page. check:docs on the rebuilt tree is green.
• declaration-map/, api-surface/, export-origins/: name-to-anchor and export maps, no line numbers and no doc text; check:generated reports all 15 artifacts up to date.
• Published type declarations: yes. The docblock lands in dist/api/index.d.ts (and .d.mts) directly above declare const DeleteDataRequestSchema (control: the [#3939] docblock on UpdateManyDataRequestSchema ships the same way), and spec publishes src/**/*.zod.ts directly via its files entry. Hence the patch changeset, marked documentation-only, following the precedent of d5d8d50db.

Verification

All on bbb1e8161; exit codes captured before any pipe; heavy runs through scripts/pm/os-verify-lock.sh with the VERDICT line read.

• pnpm --filter @objectstack/spec build — VERDICT command-exit 0 (held 152s).
• pnpm --filter @objectstack/spec check:generated — exit 0, "All 15 generated artifacts are up to date."
• pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/api/plugin-rest-api.schema-refs.test.ts src/api/protocol.test.ts src/type-alias-convention.pin.test.ts — VERDICT command-exit 0, Test Files 3 passed (3), Tests 185 passed (185).
• pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/api — VERDICT command-exit 0, Test Files 41 passed (41), Tests 1380 passed (1380).
• pnpm --filter @objectstack/spec typecheck (tsc --noEmit, check:scripts-typecheck, check:test-typecheck) — VERDICT command-exit 0.
• Gates: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands derived 67 families off the real diff (2 paths vs merge base d5d8d50db); every one was run and recorded, and --ran reconciles "67 derived, 67 run, 0 NOT-MEASURED, 0 UNRUN". 65 exited 0. Two exited 3 = PREREQUISITE NOT MET, nothing measured: check:doc-formula-expressions needed @objectstack/formula and @objectstack/lint built — built under the lock (VERDICT command-exit 0), re-run exit 0; check:dual-build-cjs-loads needs every package's dist/ (86 missing here) and has no package-scope flag — NOT MEASURED locally, CI-owned. Six further families the residue lists take a value from the workflow ($RUNNER_TEMP, matrix shards) and have no local invocation by design.
• ESLint, narrowed and measured: pnpm exec eslint --no-inline-config --format json packages/spec/src/api/protocol.zod.ts — 1 file, 0 errors, 0 warnings (eslint v10.8.1). Population read from eslint's own config: the changeset .md reports "File ignored because no matching configuration was supplied", so the diff's lintable population is exactly that one file. Invariance: eslint.config.mjs (around line 326) states the repo "never enables type-aware linting (no parserOptions.project, no typed @typescript-eslint rules) for ANY file", so a comment-only diff cannot move an untouched file's verdict.
• git status --porcelain clean after every gate; control-byte scan (grep -naP) of the diff hunk: 0 hits; check:nul-bytes exit 0.

Declared narrowing

turbo ls --affected against BASE lists 75 of 78 workspace packages — every package sits downstream of spec. Locally I ran spec's own typecheck, its src/api directory (41 files) and the three pins that read this schema; the remaining spec test files and all downstream packages' suites are declared to CI (Test Core, TypeScript Type Check). Reasoning: the diff is a comment inside a lazySchema docblock plus a changeset; nothing pins its line numbers (scripts/adr-anchors/, packages/spec/liveness, declaration-map all checked), and every artifact gate that reads the file is green.

Not done, on purpose

• [finding] p.deleteData({...} as any) / p.updateData({...} as any) erase the compile-time check of the assembled request against DeleteDataRequest / UpdateDataRequest #15866 is not addressed here — it already landed via PR fix(rest): compile the data doors' protocol requests against the declared contract #16071; the note only points at it. 请求体从不与声明它的 schema 对照(#3877 的请求侧对偶):7 个 schema 定义了从未启用,而 API 目录已宣称生效 #3899 is not addressed here — it is the decision the note records. packages/rest 的其它 req.query.* 读取点同样把 string | string[] 当字符串用(#6307 的未扩大部分) #6877 is not addressed here — it is cited from the handler's own comment.
• Reference count, measured rather than quoted: deleteData occurs in 9 non-test files across 6 package directories, 19 occurrences (git grep -l and git grep -o over packages/**/src/**, test files and test directories excluded). The cli seat's 23/11 and triage's 12/7 were taken with other scopes; none of the three numbers is written into the docblock, which names the consumer and not a count.
• Fact 3 is verified by reading — the typed literal at :8584 and the absence of any cast at the seven p.deleteData/p.updateData dispatch sites — not by a mutation experiment, which would need the @objectstack/rest typecheck closure built.

Generated by Claude Code